<!-- HTML header for doxygen 1.8.4-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
		<meta http-equiv="X-UA-Compatible" content="IE=9"/>
		<meta name="generator" content="Doxygen 1.8.4"/>
		<title>exceptions4c: e4c_st_g.h File Reference</title>
		<link href="tabs.css" rel="stylesheet" type="text/css"/>
		<link href="exceptions4c.css" rel="stylesheet" type="text/css" />
		<!-- <link href="sheep_016.png" rel="shortcut icon" /> -->
		<link href="" rel="shortcut icon">
		<script type="text/javascript" src="jquery.js"></script>
		<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
		<link href="exceptions4c.css" rel="stylesheet" type="text/css" />
	</head>
	<body>
		<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
				<div id="titlearea">
					<table cellspacing="0" cellpadding="0">
						<tbody>
							<tr style="height: 56px;">
									<td id="projectlogo"><img alt="Logo" src="sheep_064.png"/></td>
									<td style="padding-left: 0.5em;">
										<div id="projectname">
											exceptions4c
											&nbsp;
											<span id="projectnumber">version 3.0</span>
										</div>
											<div id="projectbrief">An exception handling framework for C</div>
									</td>
							</tr>
						</tbody>
				</table>
			</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.4 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li class="current"><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
  <div id="navrow2" class="tabs2">
    <ul class="tablist">
      <li><a href="files.html"><span>File&#160;List</span></a></li>
      <li><a href="globals.html"><span>Globals</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('e4c__st__g_8h.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#func-members">Functions</a>  </div>
  <div class="headertitle">
<div class="title">e4c_st_g.h File Reference</div>  </div>
</div><!--header-->
<div class="contents">

<p>exceptions4c gcc stack trace header file  
<a href="#details">More...</a></p>
<div class="textblock"><code>#include &quot;<a class="el" href="e4c_8h.html">e4c.h</a>&quot;</code><br/>
</div><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:a2605032cf2f3a853343ebabb42cfc2ba"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="e4c__st__g_8h.html#a2605032cf2f3a853343ebabb42cfc2ba">e4c_stack_trace_print_exception</a> (const <a class="el" href="structe4c__exception.html">e4c_exception</a> *exception)</td></tr>
<tr class="memdesc:a2605032cf2f3a853343ebabb42cfc2ba"><td class="mdescLeft">&#160;</td><td class="mdescRight">Prints a fatal error message and backtrace regarding the uncaught exception.  <a href="#a2605032cf2f3a853343ebabb42cfc2ba">More...</a><br/></td></tr>
<tr class="separator:a2605032cf2f3a853343ebabb42cfc2ba"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aa3d2a53c45f65c7ba688fe1714800c8d"><td class="memItemLeft" align="right" valign="top">void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="e4c__st__g_8h.html#aa3d2a53c45f65c7ba688fe1714800c8d">e4c_stack_trace_initialize</a> (const <a class="el" href="structe4c__exception.html">e4c_exception</a> *exception)</td></tr>
<tr class="memdesc:aa3d2a53c45f65c7ba688fe1714800c8d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Initializes the backtrace of a newly created exception.  <a href="#aa3d2a53c45f65c7ba688fe1714800c8d">More...</a><br/></td></tr>
<tr class="separator:aa3d2a53c45f65c7ba688fe1714800c8d"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a7f5352a2fbfe31a489e48667204faa83"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="e4c__st__g_8h.html#a7f5352a2fbfe31a489e48667204faa83">e4c_stack_trace_finalize</a> (void *custom_data)</td></tr>
<tr class="memdesc:a7f5352a2fbfe31a489e48667204faa83"><td class="mdescLeft">&#160;</td><td class="mdescRight">Finalizes the backtrace of an exception which is about to be destroyed.  <a href="#a7f5352a2fbfe31a489e48667204faa83">More...</a><br/></td></tr>
<tr class="separator:a7f5352a2fbfe31a489e48667204faa83"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p>exceptions4c gcc stack trace header file </p>
<dl class="section version"><dt>Version</dt><dd>2.0 </dd></dl>
<dl class="section author"><dt>Author</dt><dd>Copyright (c) 2012 Guillermo Calvo</dd></dl>
<h1><a class="anchor" id="e4c_st_g_h"></a>
exceptions4c gcc stack trace header file</h1>
<p>This extension allows <b>exceptions4c</b> to print a trace stack regarding an uncaught exception:</p>
<div class="fragment"><div class="line">Uncaught <a class="code" href="e4c_8h.html#a07da936a74602281d601c171b77bf0b0" title="This is the root of the exception pseudo-hierarchy ">RuntimeException</a>: He who foos last, foos best.</div>
<div class="line"></div>
<div class="line">    thrown at thud (foobar.c:9)</div>
<div class="line">    from xyzzy (foobar.c:20)</div>
<div class="line">    from plugh (foobar.c:25)</div>
<div class="line">    from fred (foobar.c:30)</div>
<div class="line">    from waldo (foobar.c:35)</div>
<div class="line">    from garply (foobar.c:40)</div>
<div class="line">    from grault (foobar.c:45)</div>
<div class="line">    from corge (foobar.c:50)</div>
<div class="line">    from quux (foobar.c:55)</div>
<div class="line">    from qux (foobar.c:63)</div>
<div class="line">    from baz (foobar.c:68)</div>
<div class="line">    from bar (foobar.c:75)</div>
<div class="line">    from foo (foobar.c:84)</div>
<div class="line">    from main (foobar.c:96)</div>
</div><!-- fragment --><p>You need to set up the provided exception context handlers through the function <code><a class="el" href="e4c_8h.html#a8fae2739e3fc3823624dc35d9ea396ae" title="Sets the optional handlers of an exception context. ">e4c_context_set_handlers</a></code>:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> *argv[]){</div>
<div class="line"></div>
<div class="line">    <a class="code" href="e4c_8h.html#a27678c11fa7d4e2a9436f527cc194013" title="Introduces a block of code which will use a new exception context. ">e4c_using_context</a>(<span class="keyword">true</span>){</div>
<div class="line"></div>
<div class="line">        e4c_context_set_handlers(</div>
<div class="line">            e4c_stack_trace_print_exception,</div>
<div class="line">            argv[0],</div>
<div class="line">            e4c_stack_trace_initialize,</div>
<div class="line">            e4c_stack_trace_finalize</div>
<div class="line">        );</div>
<div class="line"></div>
<div class="line">        <span class="comment">// ...</span></div>
<div class="line">    }</div>
<div class="line">}</div>
</div><!-- fragment --><p>This module needs to be compiled with GCC (the GNU Compiler Collection). It depends on the <em>GCC Function Instrumentation</em> and <em>Generate debugging information</em> functionality. They can be enabled by using the compiler parameters:</p>
<ul>
<li><code>-finstrument-functions</code></li>
<li><code>-g3</code></li>
</ul>
<h1><a class="anchor" id="license"></a>
License</h1>
<blockquote class="doxtable">
<p>This is free software: you can redistribute it and/or modify it under the terms of the <b>GNU Lesser General Public License</b> as published by the <em>Free Software Foundation</em>, either version 3 of the License, or (at your option) any later version.</p>
<p>This software is distributed in the hope that it will be useful, but <b>WITHOUT ANY WARRANTY</b>; without even the implied warranty of <b>MERCHANTABILITY</b> or <b>FITNESS FOR A PARTICULAR PURPOSE</b>. See the <a href="http://www.gnu.org/licenses/lgpl.html">GNU Lesser General Public License</a> for more details.</p>
<p>You should have received a copy of the GNU Lesser General Public License along with this software. If not, see <a href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>. </p>
</blockquote>
</div><h2 class="groupheader">Function Documentation</h2>
<a class="anchor" id="a7f5352a2fbfe31a489e48667204faa83"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">void e4c_stack_trace_finalize </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>custom_data</em>)</td><td></td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Finalizes the backtrace of an exception which is about to be destroyed. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">custom_data</td><td>The backtrace to be finalized</td></tr>
  </table>
  </dd>
</dl>
<p>This function disposes of the call stack captured at the moment the exception was thrown.</p>
<p>It must be passed to <code><a class="el" href="e4c_8h.html#a8fae2739e3fc3823624dc35d9ea396ae" title="Sets the optional handlers of an exception context. ">e4c_context_set_handlers</a></code> as the handler for finalizing the custom data of an exception, along with <code><a class="el" href="e4c__st__g_8h.html#aa3d2a53c45f65c7ba688fe1714800c8d" title="Initializes the backtrace of a newly created exception. ">e4c_stack_trace_initialize</a></code> and <code><a class="el" href="e4c__st__g_8h.html#a2605032cf2f3a853343ebabb42cfc2ba" title="Prints a fatal error message and backtrace regarding the uncaught exception. ">e4c_stack_trace_print_exception</a></code>.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="e4c_8h.html#a8fae2739e3fc3823624dc35d9ea396ae" title="Sets the optional handlers of an exception context. ">e4c_context_set_handlers</a> </dd>
<dd>
<a class="el" href="e4c__st__g_8h.html#aa3d2a53c45f65c7ba688fe1714800c8d" title="Initializes the backtrace of a newly created exception. ">e4c_stack_trace_initialize</a> </dd>
<dd>
<a class="el" href="e4c__st__g_8h.html#a2605032cf2f3a853343ebabb42cfc2ba" title="Prints a fatal error message and backtrace regarding the uncaught exception. ">e4c_stack_trace_print_exception</a> </dd>
<dd>
<a class="el" href="e4c_8h.html#a8ca7a4f5a33acd2bb2ed30a8d9b441de" title="Represents a function which will be executed whenever a new exception is thrown. ">e4c_initialize_handler</a> </dd>
<dd>
<a class="el" href="e4c_8h.html#ad8b769fde61d9bc8154bff6939331042" title="Represents a function which will be executed whenever an exception is destroyed. ">e4c_finalize_handler</a> </dd>
<dd>
<a class="el" href="e4c_8h.html#a06e18483913c9112424bc941e248a532" title="Represents a function which will be executed in the event of an uncaught exception. ">e4c_uncaught_handler</a> </dd></dl>

</div>
</div>
<a class="anchor" id="aa3d2a53c45f65c7ba688fe1714800c8d"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">void* e4c_stack_trace_initialize </td>
          <td>(</td>
          <td class="paramtype">const <a class="el" href="structe4c__exception.html">e4c_exception</a> *&#160;</td>
          <td class="paramname"><em>exception</em>)</td><td></td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Initializes the backtrace of a newly created exception. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">exception</td><td>The newly created exception </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>The backtrace to be assigned to the exception</dd></dl>
<p>This function captures the call stack at the moment the exception is being thrown. It expects that the initial value of the custom data is a text string containing the path to the executing program.</p>
<p>It must be passed to <code><a class="el" href="e4c_8h.html#a8fae2739e3fc3823624dc35d9ea396ae" title="Sets the optional handlers of an exception context. ">e4c_context_set_handlers</a></code> as the handler for initializing the custom data of an exception, along with <code><a class="el" href="e4c__st__g_8h.html#a7f5352a2fbfe31a489e48667204faa83" title="Finalizes the backtrace of an exception which is about to be destroyed. ">e4c_stack_trace_finalize</a></code> and <code><a class="el" href="e4c__st__g_8h.html#a2605032cf2f3a853343ebabb42cfc2ba" title="Prints a fatal error message and backtrace regarding the uncaught exception. ">e4c_stack_trace_print_exception</a></code>.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="e4c_8h.html#a8fae2739e3fc3823624dc35d9ea396ae" title="Sets the optional handlers of an exception context. ">e4c_context_set_handlers</a> </dd>
<dd>
<a class="el" href="e4c__st__g_8h.html#a7f5352a2fbfe31a489e48667204faa83" title="Finalizes the backtrace of an exception which is about to be destroyed. ">e4c_stack_trace_finalize</a> </dd>
<dd>
<a class="el" href="e4c__st__g_8h.html#a2605032cf2f3a853343ebabb42cfc2ba" title="Prints a fatal error message and backtrace regarding the uncaught exception. ">e4c_stack_trace_print_exception</a> </dd>
<dd>
<a class="el" href="e4c_8h.html#a8ca7a4f5a33acd2bb2ed30a8d9b441de" title="Represents a function which will be executed whenever a new exception is thrown. ">e4c_initialize_handler</a> </dd>
<dd>
<a class="el" href="e4c_8h.html#ad8b769fde61d9bc8154bff6939331042" title="Represents a function which will be executed whenever an exception is destroyed. ">e4c_finalize_handler</a> </dd>
<dd>
<a class="el" href="e4c_8h.html#a06e18483913c9112424bc941e248a532" title="Represents a function which will be executed in the event of an uncaught exception. ">e4c_uncaught_handler</a> </dd></dl>

</div>
</div>
<a class="anchor" id="a2605032cf2f3a853343ebabb42cfc2ba"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">void e4c_stack_trace_print_exception </td>
          <td>(</td>
          <td class="paramtype">const <a class="el" href="structe4c__exception.html">e4c_exception</a> *&#160;</td>
          <td class="paramname"><em>exception</em>)</td><td></td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Prints a fatal error message and backtrace regarding the uncaught exception. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">exception</td><td>The uncaught exception</td></tr>
  </table>
  </dd>
</dl>
<p>This function prints the exception and its backtrace to the standard error output. The stack trace represents the reverse path of execution at the moment the exception was thrown.</p>
<p>It must be passed to <code><a class="el" href="e4c_8h.html#a8fae2739e3fc3823624dc35d9ea396ae" title="Sets the optional handlers of an exception context. ">e4c_context_set_handlers</a></code> as the handler for uncaught exceptions, along with <code><a class="el" href="e4c__st__g_8h.html#aa3d2a53c45f65c7ba688fe1714800c8d" title="Initializes the backtrace of a newly created exception. ">e4c_stack_trace_initialize</a></code> and <code><a class="el" href="e4c__st__g_8h.html#a7f5352a2fbfe31a489e48667204faa83" title="Finalizes the backtrace of an exception which is about to be destroyed. ">e4c_stack_trace_finalize</a></code>.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="e4c_8h.html#a8fae2739e3fc3823624dc35d9ea396ae" title="Sets the optional handlers of an exception context. ">e4c_context_set_handlers</a> </dd>
<dd>
<a class="el" href="e4c__st__g_8h.html#aa3d2a53c45f65c7ba688fe1714800c8d" title="Initializes the backtrace of a newly created exception. ">e4c_stack_trace_initialize</a> </dd>
<dd>
<a class="el" href="e4c__st__g_8h.html#a7f5352a2fbfe31a489e48667204faa83" title="Finalizes the backtrace of an exception which is about to be destroyed. ">e4c_stack_trace_finalize</a> </dd>
<dd>
<a class="el" href="e4c_8h.html#a8ca7a4f5a33acd2bb2ed30a8d9b441de" title="Represents a function which will be executed whenever a new exception is thrown. ">e4c_initialize_handler</a> </dd>
<dd>
<a class="el" href="e4c_8h.html#ad8b769fde61d9bc8154bff6939331042" title="Represents a function which will be executed whenever an exception is destroyed. ">e4c_finalize_handler</a> </dd>
<dd>
<a class="el" href="e4c_8h.html#a06e18483913c9112424bc941e248a532" title="Represents a function which will be executed in the event of an uncaught exception. ">e4c_uncaught_handler</a> </dd></dl>

</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.4-->
<!-- start footer part -->
			<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
			  <ul>
				<li class="navelem"><a class="el" href="e4c__st__g_8h.html">e4c_st_g.h</a></li>
				<li class="footer">
					<a href="https://code.google.com/p/exceptions4c/" title="exceptions4c version 3.0">
						<img src="sheep_016.png" width="16" height="16" alt="" style="vertical-align: text-bottom;" />
						<strong>exceptions4c</strong>
					</a>
					Reference Documentation
					Generated by
					<a href="http://www.doxygen.org/index.html" title="doxygen 1.8.4">
						<strong>doxygen</strong>
					</a>
				</li>
			  </ul>
			</div>
	</body>
</html>
